Saltar al contenido principal

Wallets – Referencia del TypeScript SDK

Descripción general​

El módulo wallet en el TypeScript SDK es responsable de:

  • Representar un wallet de ULedger (Wallet / UL_Wallet)
  • Generar wallets a partir de mnemonics, keys o JSON
  • Exportar datos del wallet (WalletData) y reconstruir wallets desde datos almacenados
  • Gestionar entropía BIP-39, mnemonics y la conversión de mnemonic a seed
  • Firmar y verificar mensajes

Un wallet combina:

  • Una dirección (derivada de la public key)
  • Grupos de permisos (AuthGroups)
  • Un par de keys criptográficas (utilizadas para firmar transactions y mensajes)

El TypeScript SDK está construido sobre el Go SDK compilado a WebAssembly (WASM). Las primitivas criptográficas se ejecutan a través de un backend WASM.

Imports​

Punto de entrada principal del SDK (recomendado)​

import { initULedgerSDK, KeyType } from "@uledgerinc/typescript-sdk";

const sdk = await initULedgerSDK();
const wallet = sdk.generateWallet({ keyType: KeyType.Secp256k1 });

Imports directos del wallet (bajo nivel)​

import {
  Wallet,
  WASMBackend,
  generateMnemonic,
  validateMnemonic,
  parseAddress,
  mnemonicToSeed,
} from "@uledgerinc/typescript-sdk";

Puntos de entrada del SDK​

initULedgerSDK​

export declare function initULedgerSDK(
  config?: ULedgerSDKConfig
): Promise<ULedgerSDK>;

Inicializa el SDK con el backend WASM (punto de entrada principal de Node.js).

initULedgerSDKWithBackend​

export declare function initULedgerSDKWithBackend(
  backend: WASMBackend,
  config?: ULedgerSDKConfig
): ULedgerSDK;

Inicializa el SDK con una instancia de backend personalizada.

getULedgerSDK​

export declare function getULedgerSDK(): Promise<ULedgerSDK>;

Función de conveniencia que devuelve un ULedgerSDK inicializado.

API de wallet de ULedgerSDK​

Clase: ULedgerSDK​

export declare class ULedgerSDK {
  constructor(backend: WASMBackend, config?: ULedgerSDKConfig);

  getInfo(): SDKInfo;

  generateWallet(options?: GenerateWalletOptions): Wallet;
  walletFromMnemonic(mnemonic: string, options?: RestoreWalletOptions): Wallet;
  walletFromHex(publicKeyHex: string, privateKeyHex: string, keyType?: KeyType): Wallet;
  walletFromJson(jsonString: string, password?: string): Wallet;
  walletFromData(data: WalletData, password?: string): Wallet;

  generateMnemonic(entropyBits?: number): string;
  validateMnemonic(mnemonic: string): boolean;
  mnemonicToSeed(mnemonic: string, passphrase?: string): string;

  parseAddress(publicKeyHex: string): string;

  signMessage(
    publicKeyHex: string,
    privateKeyHex: string,
    message: string,
    keyType?: KeyType
  ): SignatureResult;

  verifySignature(
    publicKeyHex: string,
    message: string,
    signatureHex: string,
    keyType?: KeyType
  ): VerificationResult;
}

Estos métodos proporcionan los flujos de trabajo más comunes de wallet sin necesidad de importar directamente los métodos factory de Wallet.

Tipos principales​

UL_AuthPermission​

export interface UL_AuthPermission {
  create: boolean;
  read: boolean;
  update: boolean;
  delete: boolean;
}

Define permisos CRUD para un nombre de grupo determinado.

AuthGroups​

export type AuthGroups = Record<string, UL_AuthPermission>;

Un mapa de nombre de grupo → permisos.

WalletData (estructura de persistencia)​

export interface WalletData {
  address: string;
  enabled: boolean;
  parent: string;
  authGroups: AuthGroups;
  mnemonic?: string;
  keyType: KeyType;
  publicKeyHex: string;
  privateKeyHex?: string;
}

Esta es la estructura compatible con JSON utilizada para exportar/importar wallets y como entrada del wallet para la firma de transactions en WASM.

UL_Wallet​

export interface UL_Wallet {
  address: string;
  enabled: boolean;
  parent: string;
  authGroups: AuthGroups;
}

Campos públicos del wallet.

FullWallet​

export interface FullWallet extends UL_Wallet {
  mnemonic?: string;
  keyType: KeyType;
  publicKeyHex: string;
  privateKeyHex: string;
}

Estructura completa del wallet incluyendo el material de keys (contextos internos/criptográficos).

Constante de nombre de grupo Auth y helpers​

WALLET_GROUP_NAME​

export declare const WALLET_GROUP_NAME = "wallet";

createFullPermissions / createReadOnlyPermissions​

export declare function createFullPermissions(): UL_AuthPermission;
export declare function createReadOnlyPermissions(): UL_AuthPermission;

Interfaz del backend WASM (avanzado)​

Los módulos de wallet y transaction dependen de un backend WASM que implementa:

export interface WASMBackend {
  generateWallet(options: { keyType?: string; password?: string; parent?: string; entropy?: number; }): FullWallet;
  walletFromMnemonic(mnemonic: string, options: { password?: string; keyType?: string; }): FullWallet;
  walletFromHex(publicKeyHex: string, privateKeyHex: string, keyType?: string): FullWallet;
  walletFromJson(jsonString: string, password?: string): FullWallet;

  signMessage(publicKeyHex: string, privateKeyHex: string, message: string, keyType?: string): SignatureResult;
  signWithWallet(wallet: FullWallet, message: string): SignatureResult;
  verifySignature(publicKeyHex: string, message: string, signatureHex: string, keyType?: string): VerificationResult;

  parseAddress(publicKeyHex: string): { address: string };

  generateMnemonic(entropyBits?: number): { mnemonic: string };
  validateMnemonic(mnemonic: string): { valid: boolean };
  mnemonicToSeed(mnemonic: string, passphrase?: string): { seedHex: string };

  signTransactionInput(
    transactionInput: TransactionInputForSigning,
    wallet: WalletData,
    password?: string
  ): SignedTransactionInput;
}

La mayoría de los usuarios interactúan con el backend a través de ULedgerSDK y la clase Wallet.

Clase Wallet​

Clase: Wallet​

export declare class Wallet implements UL_Wallet {
  readonly address: string;
  enabled: boolean;
  parent: string;
  authGroups: AuthGroups;

  static generate(backend: WASMBackend, options?: GenerateWalletOptions): Wallet;
  static fromMnemonic(backend: WASMBackend, mnemonic: string, options?: RestoreWalletOptions): Wallet;
  static fromHex(backend: WASMBackend, publicKeyHex: string, privateKeyHex: string, keyType?: KeyType): Wallet;
  static fromJson(backend: WASMBackend, jsonString: string, password?: string): Wallet;
  static fromWalletData(backend: WASMBackend, data: WalletData, password?: string): Wallet;

  get keyType(): KeyType;
  get publicKeyHex(): string;
  get privateKeyHex(): string;
  get mnemonic(): string | undefined;

  get canSign(): boolean;

  sign(message: string): SignatureResult;
  verify(message: string, signatureHex: string): boolean;

  toWalletData(includePrivateKey?: boolean): WalletData;
  toJson(includePrivateKey?: boolean): string;

  toFullWallet(): FullWallet;
}

Creación de wallets​

sdk.generateWallet / Wallet.generate​

generateWallet(options?: GenerateWalletOptions): Wallet;
static generate(backend: WASMBackend, options?: GenerateWalletOptions): Wallet;

Genera un nuevo wallet con un mnemonic aleatorio.

GenerateWalletOptions:

export interface GenerateWalletOptions {
  keyType?: KeyType;
  password?: string;
  parent?: string;
  entropy?: number; // 128, 160, 192, 224, 256 (default: 256)
  authGroups?: AuthGroups;
}

sdk.walletFromMnemonic / Wallet.fromMnemonic​

walletFromMnemonic(mnemonic: string, options?: RestoreWalletOptions): Wallet;
static fromMnemonic(backend: WASMBackend, mnemonic: string, options?: RestoreWalletOptions): Wallet;

Restaura un wallet a partir de una frase mnemonic.

RestoreWalletOptions:

export interface RestoreWalletOptions {
  password?: string;
  keyType?: KeyType;
}

sdk.walletFromHex / Wallet.fromHex​

walletFromHex(publicKeyHex: string, privateKeyHex: string, keyType?: KeyType): Wallet;
static fromHex(backend: WASMBackend, publicKeyHex: string, privateKeyHex: string, keyType?: KeyType): Wallet;

Crea un wallet directamente desde el material de keys.

sdk.walletFromJson / Wallet.fromJson​

walletFromJson(jsonString: string, password?: string): Wallet;
static fromJson(backend: WASMBackend, jsonString: string, password?: string): Wallet;

Analiza un wallet desde una cadena JSON (que normalmente coincide con la estructura WalletData). Este es el análogo en TS de wallet.FromJson de Go.

sdk.walletFromData / Wallet.fromWalletData​

walletFromData(data: WalletData, password?: string): Wallet;
static fromWalletData(backend: WASMBackend, data: WalletData, password?: string): Wallet;

Crea un wallet desde un objeto WalletData ya analizado.

Exportación y serialización​

wallet.toWalletData(includePrivateKey?)​

toWalletData(includePrivateKey?: boolean): WalletData;
  • includePrivateKey = false → omite privateKeyHex
  • includePrivateKey = true → incluye privateKeyHex

wallet.toJson(includePrivateKey?)​

toJson(includePrivateKey?: boolean): string;

Exporta el wallet como una cadena JSON.

Utilidades de mnemonic y dirección​

sdk.generateMnemonic​

generateMnemonic(entropyBits?: number): string;

Genera un mnemonic BIP-39.

sdk.validateMnemonic​

validateMnemonic(mnemonic: string): boolean;

Valida un mnemonic BIP-39.

sdk.mnemonicToSeed​

mnemonicToSeed(mnemonic: string, passphrase?: string): string;

Convierte un mnemonic más una passphrase opcional en un seed (hex).

sdk.parseAddress​

parseAddress(publicKeyHex: string): string;

Calcula la dirección a partir de la public key.

Firma y verificación de mensajes​

sdk.signMessage​

signMessage(
  publicKeyHex: string,
  privateKeyHex: string,
  message: string,
  keyType?: KeyType
): SignatureResult;

Firma un mensaje usando key hex en bruto.

sdk.verifySignature​

verifySignature(
  publicKeyHex: string,
  message: string,
  signatureHex: string,
  keyType?: KeyType
): VerificationResult;

Verifica una firma usando una public key.

Esta página está pensada como referencia. Para guías paso a paso consulta nuestra sección de tutoriales.